/****************************************************************************** 
 * @file rd0ff_bsp_key_handler.c 
 * @brief KEY处理器实现文件 
 * 
 * 详细描述： 
 * - 功能1：实现KEY数据采集与处理的核心算法 
 * - 功能2：提供按键控制逻辑与事件响应机制 
 * - 功能3：实现FreeRTOS线程管理与队列通信 
 * - 功能4：集成KEY状态检测与按键事件处理 
 * 
 * @author 陈泳行 | R&D Dept. | Jin Dou Aerospace 金斗航天 
 * @date 2025-6-29 
 * @version 1.0.0 
 * 
 * @version_history 
 * - 1.0.0 (2025-6-29): 初始版本，实现基本功能 
 * 
 * @note 本模块依赖KEY驱动层和FreeRTOS操作系统 
 * @warning 线程函数必须在操作系统环境下调用，禁止直接调用 
 ******************************************************************************/
#include "rd0ff_bsp_key_handler.h"

key_handler_ret_t key_scan(bsp_key_handler_t * self);

key_handler_ret_t key_register(bsp_key_handler_t *				    self,
                              bsp_key_driver_t  * 				  driver,
                              key_index_t		 *				   index );

static key_handler_ret_t __key_register_init( bsp_key_driver_t *regist[],
                                             uint32_t		        size );

/**
 * @brief KEY处理器实例初始化函数
 *
 * 初始化KEY处理器实例，验证输入参数，绑定硬件接口和OS接口，
 * 完成私有数据分配和初始化状态设置。
 *
 * @param self KEY处理器实例指针
 * @param input 初始化输入参数结构体指针
 * @return key_handler_ret_t 操作结果状态码
 * @retval KEY_HANDLER_RET_OK 初始化成功
 * @retval KEY_HANDLER_RET_INVALID_PARAM 输入参数无效
 * @retval KEY_HANDLER_RET_ERROR 初始化失败或内存分配失败
 */
key_handler_ret_t bsp_key_handler_inst(bsp_key_handler_t *self,
                                     key_handler_input_t *input)
{
    key_handler_ret_t ret = KEY_HANDLER_RET_OK;

    // 关键变量注释
    // self->init_status: 初始化状态
    // self->key_instance.p_time_base_ms: 时间基准指针
    // self->key_instance.p_os_time_delay: OS延时指针
    // self->key_instance.p_os_queue: OS队列指针
    // self->key_instance.p_os_thread: OS线程指针
    // self->key_instance.p_os_critical: OS临界指针

    // 1.判断是否是野指针
    if(self == NULL || input == NULL)
    {
        ret = KEY_HANDLER_RET_ERROR;
        return ret;
    }

    // 2.判断是否是初始化
    if(KEY_HANDLER_INIT == self->init_status)
    {
        ret = KEY_HANDLER_RET_ERROR;
        return ret;
    }

    // 3.设置LED驱动实例参数
    // 外部传入
    self->p_time_base_ms  = input->p_time_base_ms;
#ifdef OS_SUPPIRTING_KEY
    self->p_os_time_delay = input->p_os_time_delay;
    self->p_os_queue      = input->p_os_queue;
    self->p_os_thread     = input->p_os_thread;
    self->p_os_critical   = input->p_os_critical;
#endif // OS_SUPPIRTING
    // 内部传入
    self->key_read     = key_scan; // 调用此函数的时候将参数添加进去轮询 
                               // 需要解决多个按键轮询消抖问题
    self->register_key = key_register;

    self->p_os_queue->pf_os_create_queue(50,
										 sizeof(key_event_t),
										 &self->handle_queue );///< 创建队列
	if(NULL == self->handle_queue) return KEY_HANDLER_RET_ERROR;
    // 留给外部写 实现解耦
    self->p_os_thread->pf_os_create_thread(input->thread,
										   input->thread_name,
										   input->stack_depth,
										   self,
										   input->priority,
										   &self->handle_thread );///< 创建线程

    // 4.初始化KEY驱动实例
    self->key_instance.key_num = 0;// 注册设备重置
    ret = __key_register_init(self->key_instance.\
							  pa_register_group,
                              KEY_REGISTER_MAX);
    if( KEY_HANDLER_RET_OK != ret )
	{
		self->p_os_queue->pf_os_delet_queue\
                        (&self->handle_queue);///< 删除队列
		self->p_os_thread->pf_os_delet_thread\
                        (&self->handle_thread);///<删除线程
		return KEY_HANDLER_RET_ERROR;
	}

    self->init_status = KEY_HANDLER_INIT;  ///< 设置为已初始化状态
    return KEY_HANDLER_RET_OK;
}

/**
 * @brief ADDA处理器实例初始化函数
 *
 * 初始化ADDA处理器实例，验证输入参数，绑定硬件接口和OS接口，
 * 完成私有数据分配和初始化状态设置。
 *
 * @param adda_handler ADDA处理器实例指针
 * @param adda_input 初始化输入参数结构体指针
 * @return adda_handler_ret_t 操作结果状态码
 * @retval ADDA_HANDLER_RET_OK 初始化成功
 * @retval ADDA_HANDLER_RET_INVALID_PARAM 输入参数无效
 * @retval ADDA_HANDLER_RET_ERROR 初始化失败或内存分配失败
 */
static key_handler_ret_t __key_register_init( bsp_key_driver_t *regist[],
                                             uint32_t		        size )
{
    uint32_t i;
    for(i = 0; i < KEY_REGISTER_MAX; i++)
        regist[i] = (bsp_key_driver_t *)KEY_REGISTER_INIT; // 初始化为默认值
    
    return KEY_HANDLER_RET_OK;
}   

/**
 * @brief ADDA处理器实例初始化函数
 *
 * 初始化ADDA处理器实例，验证输入参数，绑定硬件接口和OS接口，
 * 完成私有数据分配和初始化状态设置。
 *
 * @param adda_handler ADDA处理器实例指针
 * @param adda_input 初始化输入参数结构体指针
 * @return adda_handler_ret_t 操作结果状态码
 * @retval ADDA_HANDLER_RET_OK 初始化成功
 * @retval ADDA_HANDLER_RET_INVALID_PARAM 输入参数无效
 * @retval ADDA_HANDLER_RET_ERROR 初始化失败或内存分配失败
 */
key_handler_ret_t key_register(bsp_key_handler_t *				    self,
                              bsp_key_driver_t  * 				  driver,
                              key_index_t		 *				   index )
{
    // 1.判断是否是野指针
    if(KEY_HANDLER_NO_INIT == self->init_status   ||
       NULL 			   == self  			  ||
       NULL 			   == driver 			  	)
    {
        return KEY_HANDLER_RET_ERROR;
    }
    
    // 2.检查Driver是否未初始化
    if(KEY_NOT_INIT == driver->init_status)
    {
        return KEY_HANDLER_RET_ERROR;
    }
    
    // 3.检查是否超出挂载数量
    if(KEY_REGISTER_MAX <= self->key_instance.key_num)
    {
        return KEY_HANDLER_RET_ERROR;
    }
    
#ifdef OS_SUPPIRTING_KEY
//    self->p_os_critical->pf_os_critical_enter();// 进入临界区
#endif // OS_SUPPIRTING
	
    // 4.挂载KEY驱动
    if(KEY_REGISTER_MAX > self->key_instance.key_num)
    {
        self->key_instance.pa_register_group[self-> \
                       key_instance.key_num] = driver;
        
        *index = (key_index_t)self->key_instance.key_num;
        
        self->key_instance.key_num++;
    }
    
#ifdef OS_SUPPIRTING_KEY
//    self->p_os_critical->pf_os_critical_exit(); // 退出临界区
#endif // OS_SUPPIRTING
    
    return KEY_HANDLER_RET_OK;
}
